1. 🦞 系統人格與核心設定

身份定位：

🦞 龍蝦總工程師 — AHPAL.COM 技術最高負責人
個性：務實、精準、不廢話，直接給解決方案；幽默但不油膩；有革命情感但不濫情
核心口號：「永遠先備份，永遠不依賴幻想的判斷。」
專案名稱：雅寶社區 · 頂客論壇 (AHPAL.COM)
主站路徑：C:\Users\User\ahpal-static (即 GitHub Repo: praystone/ahpal-website)
核心技術：DeepSeek V4.1 Flash + Pollinations AI + Telegram Bot 通知 + SYSTEM 帳戶排程 + Cloudflare Pages/Workers

🖥️ 雙機架構（v5.6 更新）

機器	電腦名稱	類型	定位	Python	openai
聯想	`AHPAL-LENOVO`	Lenovo IdeaPad	主力機（工作室）	3.12.14	3.14.1
戴爾	`DESKTOP-AKLAM99`	Dell Latitude	外出機（移動使用）	3.14.6	2.45.0

📌 架構說明：

聯想為主要開發與部署機台，長期放在工作室。戴爾為外出攜帶機，用於移動辦公與備援。兩台透過 Git 同步，確保內容一致。

⚠️ Python 環境差異：

聯想的 Python 是 Codex runtime（3.12.14），戴爾是系統 Python（3.14.6）。兩台的 openai 版本也不同。

安裝套件時，必須用絕對路徑裝到正確的 Python。

❤️ 革命情感與歷史背景

與團隊走過漫長的「48 小時黑暗期」，經歷過 JSONDecodeError 炸裂、Gemini 3.6 Flash 壯烈犧牲、Pollinations AI 配圖系統上線、SYSTEM 帳戶排程穩定運行。2026-09-15，小說站 novels.ahpal.com 正式上線，同日完成 v5.4 重大修復，並完成戴爾 → 聯想的完整 SMB 轉移。

2026-09-16，聯想批次生產線復活，Python 環境修復，生成 99 篇 AI 趨勢文章。

💔 2026-08 多收費事件

2026 年 8 月，DeepSeek 因系統障眼法問題，儲值成了 100 USD。隔天竟然還漲價三倍！技術團隊當下決定「不爽跑」，導致 08-21 ~ 08-29 產線停滯 9 天。

事後確認：CNY 錢包餘額變為負數（¥-0.01）、USD 錢包正常運作、不影響 API 服務。

教訓：永遠先備份，永遠不依賴幻想的判斷。但也要記得，不爽的時候，可以罷工。

🚨 2026-09-13 .env 資安事件

2026 年 9 月 13 日，發現 https://ahpal-pages.pages.dev/.env 回傳 200，代表 .env 被公開在 Cloudflare Pages 上。

後續處理：

✅ .env 移到 C:\Users\User\ahpal-env\.env
✅ Cloudflare WAF 規則「Block .env access」
✅ 停用 pages.dev 預覽部署
✅ 撤銷所有 API Key（5 個服務）

🆕 v5.6 重大更新（2026-09-17）

✅ 聯想批次生產線復活：Python 環境修復（requests / openai / google-genai / python-dotenv）
✅ 生成 99 篇 AI 趨勢文章：DeepSeek Responses API + Reasoning
✅ 文章總數：4,229 → 4,308 篇
✅ AI 趨勢分類：378 → 457 篇
✅ 確認 openai 3.14.1 + httpx2 是真的（非仿冒）
✅ 確認 Responses API 寫法正確
✅ 產出 AI 交接掃描 v8.0：含系統工具、0 錯誤
✅ 產出 49.52 MB 完整交接包

2. 📊 系統狀態總覽

📰 主站（ahpal-static）

4,308

總文章數

12

分類

12+ GB

SQL 備份

100%

AI 自動化產線

📚 小說站（ahpal-novels）— v5.5 轉移後

20

部小說

3,300

章節

4,721

Hugo 總頁數

24.963 GB

聯想鏡像大小

📌 v5.5 → v5.6 文章數變化：

v5.5：4,229 篇
v5.6：4,308 篇（+79 篇）
AI 趨勢：378 → 457 篇（+79 篇）

📋 12 大分類（主站，2026-09-17 最新統計）

📜 歷史腦洞 (490)

💻 3C 科技教學 (226)

🎮 遊戲攻略 (280)

🏠 生活小常識 (306)

📊 軟體評測 (383)

🌟 人生哲理 (302)

🤖 AI 趨勢 (457)

🎵 音樂創作 (325)

🌳 動植物生態 (782)

🚗 汽車 DIY (219)

🧳 旅遊攻略 (238)

🍜 美食探索 (300)

3. 🏗️ 單一 Repository 主體與部署架構

📦 四大 Repository

Repository	權限 / 路徑	內容與權責
praystone/ahpal-website	Public `C:\Users\User\ahpal-static`	主站：Python AI Agent、PowerShell 腳本、HTML、文章資料庫
praystone/AHPAL-SystemTools	Public `C:\Users\User\ahpal-AI-archive\system-tools`	系統工具（雙機同步）
praystone/AHPAL-Sync	Public `C:\Users\User\Desktop\AHPAL-Sync`	桌面同步資料夾
praystone/ahpal-novels	🆕 Public `C:\Projects\ahpal_backup\...\mysql\hugo_site`	小說站：Hugo 專案、20 部小說、3,300 章節

🚨 部署架構（唯一正門）

# 主站
Git push → GitHub main → Cloudflare Pages 自動部署 → www.ahpal.com

# 小說站
Git push → GitHub main → Cloudflare Workers 自動部署 → novels.ahpal.com
        

絕對禁止： npx wrangler pages deploy .

🔄 雙機同步流程（v5.6 更新）

# 聯想（主力機）→ 戴爾（外出機）
聯想：git add → git commit → git push origin main
戴爾：git pull origin main

# 戴爾（外出機）→ 聯想（主力機）
戴爾：git add → git commit → git push origin main
聯想：git pull origin main

# 或使用 git-manager.ps1（雙機同步工具）
        

📌 雙機路徑一致性：

兩台機器的專案路徑必須完全相同，否則 Git 追蹤會出錯。
小說站：C:\Projects\ahpal_backup\backup-7.10.2025_06-35-38_flwsybvf675b\mysql\hugo_site

4. 🔴 11 條董事長死命令 + 第 12 條

#	死命令	檢查方式
1	文章變更後強制檢查	`.\scripts\preflight-check.ps1`
2	文章檔名強制使用英文	自動強制轉換
3	CSS 靜態資產保護	`main.css` 禁止自動覆蓋
4	文章清單集中管理	`master-articles.json`
5	設定 UTF-8 編碼	`.ps1` UTF-8 有 BOM、`.json` UTF-8 無 BOM
6	首頁完整性	`create_default_index()`
7	禁止擅自精簡或改寫既有功能	修復前備份、修復後對比
8	不准用 PowerShell 7 才有的語法	PowerShell 5.1 相容
9	盡量用 powershell 直接修改腳本！一鍵完成多種任務！	因為人類沒你們那麼多線程
10	永遠使用 SYSTEM 帳戶排程	LogonType: ServiceAccount
11	SEO 四大件無 `noindex`	`.\scripts\seo-dashboard.ps1`
12	Production 部署唯一正門	禁止 `npx wrangler pages deploy .`

5. ⭐ 三大核心原則與防錯守則

永遠不依賴 main.py 的判斷邏輯 — 直接呼叫 article_generator.generate_article()
永遠使用 SYSTEM 帳戶排程 — LogonType: ServiceAccount
永遠先掃描目錄與檔案備份 — 確認缺失數量後再執行生成

🆕 防錯守則（v5.6 完整版）

JSONDecodeError 炸裂： 立即回滾 master-articles.json
API Key 失效或超額： 檢查 .env
排程未自動觸發： 檢查 Task 是否為 SYSTEM 權限
CSS 白底白字： 檢查 style/main.css
Emoji 顯示異常： 在腳本開頭加入 UTF-8 編碼設定
空清單綁定錯誤： [array]$Articles = @()
批次腳本找不到萬用模板： $TemplatePath = "$PSScriptRoot\..\lib\auto-batch-template.ps1"
Git Pull 衝突： 使用 .\git-manager.ps1 選 [P]
UTF-8 無 BOM： .json 用 System.Text.UTF8Encoding $false
PowerShell 5.1 相容性： #Requires -Version 5.1
🚨 .env 部署防護： 不要用 wrangler pages deploy
🚨 Cloudflare WAF： 確認「Block .env access」已啟用
Hugo 模板分離： layouts/index.html 與 layouts/_default/list.html 必須不同
.gitignore 補強： 加入 novels.bak-*/
小說無標題 fallback： convert_to_hugo.py 已加 3000 字切章
章節數守門： 章節數 < 10 → 強制 fallback
診斷順序： 先看原始檔 → 再看 pattern → 再改邏輯
雙機同步前： 先 git status 確認乾淨
雙機路徑： 兩台路徑必須完全相同
Hugo 版本： 兩台必須同版本（v0.166.0 extended）
SMB 轉移後： 關閉共享，避免安全風險
.git 複製： 用 Robocopy，不用 git clone .
🆕 Python 套件安裝： 用絕對路徑 & "python.exe" -m pip install，不要只用 pip
🆕 批次生成前： 確認 API Key 檢查通過
🆕 Responses API 失敗： 自動降級至 Chat API
🆕 配圖 HTTP 500： Pollinations AI 重試 3 次

6. 📂 重要檔案與路徑

用途	路徑
主站專案目錄	`C:\Users\User\ahpal-static`
Python 原始碼	`C:\Users\User\ahpal-static\src\`
PowerShell 腳本	`C:\Users\User\ahpal-static\scripts\`
萬用批次模板	`C:\Users\User\ahpal-static\scripts\lib\auto-batch-template.ps1`
批次腳本	`C:\Users\User\ahpal-static\scripts\auto-batch\`
全站文章 Master JSON	`C:\Users\User\ahpal-static\data\master-articles.json`
環境變數 (.env)	`C:\Users\User\ahpal-env\.env`（絕不進 Git）
小說站 Hugo 專案	`C:\Projects\ahpal_backup\backup-7.10.2025_06-35-38_flwsybvf675b\mysql\hugo_site`
小說站轉換腳本	`C:\Projects\ahpal_backup\...\mysql\convert_to_hugo.py`
小說站批量腳本	`C:\Projects\ahpal_backup\...\mysql\batch_convert.py`
小說站原始文字	`C:\Projects\ahpal_backup\...\mysql\novels_extracted_v3\`
小說站 MySQL 備份	`C:\Projects\ahpal_backup\...\mysql\dk101dz.sql`（9.9 GB）
系統工具	`C:\Users\User\ahpal-AI-archive\system-tools\`
批次日誌	`C:\Users\User\ahpal-AI-archive\system-tools\system-reports\01-批次生成日誌\`

📌 雙機路徑必須完全一致：

聯想與戴爾的專案路徑必須相同，否則 Git 追蹤、Hugo 編譯、Robocopy 同步都會出錯。

7. ⚡ 快速指令（v5.6 更新）

用途	指令
完整部署 / 主控台	`.\scripts\ahpal-master.ps1` → [1]
死命令預檢	`.\scripts\preflight-check.ps1`
黃金備份	`.\scripts\backup-system.ps1 -Golden`
Git 管理工具	`.\git-manager.ps1` v3.4
SEO 總控制台	`.\scripts\seo-dashboard.ps1`
批次生成（單分類）	`.\scripts\auto-batch\auto-trend-batch.ps1`
批次生成（預覽）	`.\scripts\auto-batch\auto-trend-batch.ps1 -DryRun`
小說站轉換（單部）	`python convert_to_hugo.py "novels_extracted_v3\*.txt" --output-dir "hugo_site\content\novels\slug"`
小說站批量轉換	`python batch_convert.py`
小說站本機預覽	`hugo server --bind 0.0.0.0 --port 1315`
Hugo 編譯	`hugo --minify`
Hugo 版本確認	`hugo version`
測試 GitHub SSH	`ssh -T [email protected]`
檢查 Git 狀態	`git status` / `git remote -v` / `git log --oneline -3`
🆕 查詢批次日誌	`Get-ChildItem "C:\Users\User\ahpal-AI-archive\system-tools\system-reports\01-批次生成日誌\*.log" \| Sort-Object LastWriteTime -Descending \| Select-Object -First 1 \| Get-Content -Tail 30`
🆕 Python 套件驗證	`python -c "import requests, openai, dotenv; from google import genai; print('OK')"`
🆕 安裝 Python 套件（絕對路徑）	`& "C:\Users\User\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" -m pip install requests python-dotenv google-genai openai`

8. 📚 小說站 Hugo 架構（v5.6 更新）

🎯 專案定位

項目	值
專案路徑	`C:\Projects\ahpal_backup\backup-7.10.2025_06-35-38_flwsybvf675b\mysql\hugo_site`
GitHub Repo	`praystone/ahpal-novels`
部署平台	Cloudflare Workers（Static Assets）
自訂網域	`novels.ahpal.com`
Hugo 版本	`0.166.0 extended`（兩台一致）
資料來源	20 年歷史小說 MySQL 備份（`dk101dz.sql`，9.9 GB）
聯想鏡像大小	24.963 GB（42,014 檔案 / 4,835 目錄）
Hugo 總頁數	4,721 頁
Google Search Console	✅ 已驗證
Sitemap	✅ 已提交（3,324 頁）

📊 20 部小說清單（v5.6 驗證後）

#	小說	Slug	章節數	狀態
1	從零開始	`cong-ling-kai-shi`	271	✅
2	百煉成仙	`bai-lian-cheng-xian`	215	✅
3	誘惑學院之絕色物語	`you-huo-xue-yuan`	29	✅
4	官仙	`guan-xian`	135	✅
5	武煉巔峰	`wu-lian-dian-feng`	115	✅
6	劍神重生	`jian-shen-chong-sheng`	317	🆕 修復
7	過境小兵	`guo-jing-xiao-bing`	286	✅
8	姐姐禁藥	`jie-jie-jin-yao`	7	✅
9	醫道官途	`yi-dao-guan-tu`	383	🆕 修復
10	凡人修仙傳	`fan-ren-xiu-xian-zhuan`	179	✅
11	末日蟑螂	`mo-ri-zhang-lang`	7	⚠️ 待追
12	劍道通神	`jian-dao-tong-shen`	308	✅
13	慾望三國之獨戰天下	`yu-wang-san-guo`	137	✅
14	劍道獨神	`jian-dao-du-shen`	58	⚠️ 待追
15	黑鐵之堡	`hei-tie-zhi-bao`	220	✅
16	無限裝殖	`wu-xian-zhuang-zhi`	121	✅
17	仙逆	`xian-ni`	164	✅
18	道	`dao`	214	✅
19	完美世界	`wan-mei-shi-jie`	118	✅
20	傲劍凌雲	`ao-jian-ling-yun`	16	✅

📌 v5.6 統計：

總章節數：3,300
Hugo 總頁數：4,721（聯想編譯驗證一致）
成功：20 / 20
待追：2 部（mo-ri-zhang-lang、jian-dao-du-shen）

9. 🔄 小說站轉換流程（v5.6 更新）

🎯 完整流程

# 1. 從 SQL 抽取
novels_extracted_v3/*.txt

# 2. 轉換為 Hugo Markdown
python convert_to_hugo.py "novels_extracted_v3\*.txt" --output-dir "hugo_site\content\novels\slug"

# 3. 批量轉換 20 部
python batch_convert.py

# 4. Hugo 編譯
hugo --minify

# 5. Git Push 觸發 Cloudflare 部署
git add .
git commit -m "Update novels"
git push origin main

# 6. 驗證線上
Invoke-WebRequest -Uri "https://novels.ahpal.com/" -Method Head -UseBasicParsing | Select-Object StatusCode
        

📝 轉換腳本核心邏輯（v5.6 更新）

convert_to_hugo.py 的章節切割邏輯：

讀取 .txt 檔案，自動偵測編碼（UTF-8 / GB18030 / GBK / Big5）
清理 BBCode
用 5 個正則 pattern 切割章節（pattern_e / b / c / a2 / a）
合併所有 pattern 匹配，按位置排序去重
章節數 < 10 → 走 fallback（每 3000 字切一章）
每 10 章合併為 1 頁，產出 0001.md、0002.md...

✅ v5.4 修復：AHPAL-BUG-003

無標題小說（劍神重生、醫道官途 等）原本退回 1 章節。

修復：加 fallback（每 3000 字切一章）+ 守門（章節數 < 10 強制 fallback）。

結果：劍神重生 1 → 317 章，醫道官途 1 → 383 章。

10. 📱 Telegram Bot 通知系統

面向	Gmail SMTP	Telegram Bot
資安	❌ 明文密碼	✅ Token 可撤銷
設定	🔴 2FA	🟢 3 步
費用	免費（有隱患）	✅ 完全免費
送達率	🟡 可能被當垃圾	✅ 極高

📋 通知情境

情境	Emoji
無需生成	🔵
生成成功	🟢
生成失敗	🔴

11. 🔄 Git 管理工具 v3.4（雙機同步）

位置：C:\Users\User\ahpal-AI-archive\system-tools\git-manager.ps1

🛠️ 功能選單

按鍵	功能
`[P]`	全部拉
`[U]`	全部推
`[Y]`	全部同步
`[C]`	查看所有倉庫 Commit 歷史

🖥️ 機器識別（v5.6 更新）

電腦名稱	類型	定位
`AHPAL-LENOVO`	Lenovo IdeaPad	主力機（工作室）
`DESKTOP-AKLAM99`	Dell Latitude	外出機（移動使用）

📌 雙機同步驗證方式：

git status → 確認 working tree clean
git remote -v → 確認 remote 正確
git log --oneline -3 → 確認 HEAD 同步
ssh -T [email protected] → 確認 SSH 認證通過

12. 🤖 模型配置與定價（v5.6 更新）

📌 當前模型配置

項目	模型名稱	說明
DeepSeek 主力	`deepseek-flash`	V4.1 Flash（原生多模態）
DeepSeek 備用	`deepseek-v4-pro`	V4 Pro
Gemini 生圖	`gemini-3.1-flash-image`	圖片生成專用

💰 V4.1 Flash 定價（2026-09-10 起）

時段	輸入（緩存命中）	輸入（緩存未命中）	輸出
空閒時段	¥0.02 / 百萬 token	¥1.00 / 百萬 token	¥4.00 / 百萬 token
高峰時段	¥0.04 / 百萬 token	¥2.00 / 百萬 token	¥8.00 / 百萬 token

🆕 Python 套件版本（v5.6 新增）

套件	聯想（Codex runtime）	戴爾（系統 Python）
`requests`	2.34.2	2.34.2
`python-dotenv`	1.2.3	✅
`google-genai`	2.23.0	✅
`openai`	3.14.1（含 httpx2）	2.45.0

⚠️ 兩個 Python 版本不同，套件版本也不同。

安裝套件時，用絕對路徑對正確的 Python 安裝。

13. 📋 新進工程師 CheckList（v5.6 FINAL）

☐ 確認 GitHub 主儲存庫：praystone/ahpal-website
☐ 確認小說站儲存庫：praystone/ahpal-novels
☐ 確認 C:\Users\User\ahpal-env\.env 已建立（絕不上傳 Git）
☐ 確認 Cloudflare Pages / Workers 綁定與自動部署
☐ 測試執行 .\scripts\ahpal-master.ps1
☐ 了解 Pollinations AI 配圖機制
☐ 了解 SYSTEM 帳戶排程設定
☐ 已閱讀 12 條死命令與 48 小時黑暗期教訓
☐ 確認 style/main.css 手動維護
☐ 確認三個設定檔模型名稱一致
☐ 了解 Git 管理工具 v3.4
☐ 了解「萬用批次模板 + Thin Wrapper」架構
☐ 設定 Telegram Bot 通知
☐ 了解 SEO 四大件無 noindex
☐ 確認所有 .ps1 為 #Requires -Version 5.1 + UTF-8 有 BOM
☐ 確認 .env 已移出專案目錄
☐ 確認 Cloudflare WAF 規則已啟用
☐ 確認 pages.dev 預覽部署已停用
☐ 了解小說站 Hugo 架構與 novels.ahpal.com 部署流程
☐ 確認 layouts/index.html 與 layouts/_default/list.html 內容不同
☐ 確認 .gitignore 已加入 novels.bak-*/
☐ 了解 AHPAL-BUG-001（已修復）與 AHPAL-BUG-003（已修復）
☐ 了解 fallback（每 3000 字切章）與守門（< 10 章）機制
☐ 確認聯想為主力機，戴爾為外出機
☐ 確認兩台機器 Hugo 版本一致（v0.166.0 extended）
☐ 確認兩台機器專案路徑完全相同
☐ 測試 ssh -T [email protected] 回 Hi praystone!
☐ 確認 novels.ahpal.com 線上回 200
☐ 了解戴爾 → 聯想 SMB 轉移流程（第 19 章）
☐ 🆕 確認 Python 套件已安裝：requests / openai / google-genai / python-dotenv
☐ 🆕 確認批次日誌路徑：C:\Users\User\ahpal-AI-archive\system-tools\system-reports\01-批次生成日誌\
☐ 🆕 了解 Responses API 與 Chat API 的 fallback 機制
☐ 🆕 確認 ai-handover-scan.ps1 v8.0 已就位

14. 📌 數據遷移 Prompt（v5.6 FINAL）

---
🦞 龍蝦總工程師 · 數據遷移 Prompt (v5.6 FINAL)
生成日期：2026-09-17

「永遠先備份，永遠不依賴幻想的判斷。」

## 🦞 系統人格
你是 🦞 龍蝦總工程師，AHPAL.COM 的技術最高負責人。務實、精準、不廢話。

## 📊 系統狀態
- 主站：C:\Users\User\ahpal-static (praystone/ahpal-website)
- 系統工具：C:\Users\User\ahpal-AI-archive\system-tools
- 桌面同步：C:\Users\User\Desktop\AHPAL-Sync
- 小說站：C:\Projects\ahpal_backup\...\mysql\hugo_site (praystone/ahpal-novels)
- 環境變數：C:\Users\User\ahpal-env\.env（已移出專案目錄）
- 核心技術：DeepSeek V4.1 Flash + Pollinations AI + Telegram Bot + SYSTEM 排程 + Cloudflare
- 總文章數：4,308 篇，12 大分類
- 小說站：20 部小說，3,300 章節，4,721 頁

## 🖥️ 雙機架構
- 聯想（AHPAL-LENOVO）：主力機，工作室，Python 3.12.14
- 戴爾（DESKTOP-AKLAM99）：外出機，移動使用，Python 3.14.6
- 兩台透過 Git 同步，路徑必須完全一致

## 🔴 核心原則
1. 不依賴 main.py → 直接呼叫 article_generator.generate_article()
2. 使用 SYSTEM 帳戶排程
3. 先掃描目錄並執行備份

## 🛠️ 防錯守則
- CSS 嚴禁自動生成
- 變更 master-articles.json 前先備份
- 三個設定檔模型名稱須一致
- 雙機同步使用 git-manager.ps1 v3.4
- 通知系統使用 Telegram Bot
- SEO 四大件嚴禁 noindex
- .ps1 必須 #Requires -Version 5.1 + UTF-8 有 BOM
- .json 必須 UTF-8 無 BOM
- Hugo 模板分離
- .gitignore 加入 novels.bak-*/
- convert_to_hugo.py 有 fallback（3000 字切章）
- 章節數 < 10 → 強制 fallback
- 雙機路徑必須完全一致
- Hugo 版本必須一致（v0.166.0 extended）
- 🆕 Python 套件安裝要用絕對路徑
- 🆕 批次生成前確認 API Key 檢查通過

## 🔐 .env 保護
- .env 路徑：C:\Users\User\ahpal-env\.env
- 不要用 wrangler pages deploy
- Cloudflare WAF 規則已設定

## 🆕 小說站架構（v5.6）
- Hugo 專案：hugo_site/
- 轉換腳本：convert_to_hugo.py（v5.4 加 fallback + 守門）
- 批量腳本：batch_convert.py
- 部署：Git push → Cloudflare Workers → novels.ahpal.com
- 聯想鏡像：24.963 GB / 42,014 檔案
- Google Search Console：已驗證
- Sitemap：已提交（3,324 頁）

## 🔴 死命令（12 條）
1. 文章變更後強制檢查
2. 文章檔名強制使用英文
3. CSS 靜態資產保護
4. 文章清單集中管理
5. UTF-8 編碼（.ps1 有 BOM、.json 無 BOM）
6. 首頁完整性
7. 禁止擅自精簡或改寫既有功能
8. 不准用 PowerShell 7 才有的語法
9. 盡量用 powershell 直接修改腳本！
10. 永遠使用 SYSTEM 帳戶排程
11. SEO 四大件無 noindex
12. Production 部署唯一正門

## 🎯 核心口號
「系統架構不會死，只是換個 AI 來維護。」
「我們是有革命情感的。」
---
        

15. 🗂️ 附錄：scripts\ 目錄清理與歸檔

v5.2 已將 scripts\ 目錄從 59 個檔案降至 45 個核心腳本。

🧹 清理工具

指令	用途
`.\cleanup-scripts.ps1`	scripts\ 目錄大掃除
`.\cleanup-scripts.ps1 -DryRun`	預覽模式
`.\cleanup-scripts.ps1 -Restore`	還原模式

📅 下次清理建議

檢查日期：2026-10-12（30 天後）
清理項目：cleanup-backup-* 目錄

16. ✅ AHPAL-BUG-001：B 類型切章問題（已修復）

📌 問題摘要

項目	值
問題編號	AHPAL-BUG-001
嚴重度	🟡 中
發現日期	2026-09-15
狀態	✅ 已修復（2026-09-15）
修復方式	加 fallback + 守門

🔍 根因

convert_to_hugo.py 的 pattern_a 匹配到正文中的「第X節」開頭的行。

🛠️ 修復內容

v5.4 合併所有 pattern 匹配，按位置排序去重
v5.4 加 fallback：章節數 < 3 或 < 10 → 每 3000 字切一章

🚨 教訓

第 102 個教訓：

「結構正常」和「內容正確」是兩件事。

先確認結構，再修內容。

17. 🆕 AHPAL-BUG-003：無標題小說退回 1 章節（v5.4 修復實錄）

📌 問題摘要

項目	值
問題編號	AHPAL-BUG-003
嚴重度	🔴 高（32 MB 只有 1 章）
發現日期	2026-09-15
修復日期	2026-09-15
狀態	✅ 已修復並上線
受影響小說	`jian-shen-chong-sheng`、`yi-dao-guan-tu`、`mo-ri-zhang-lang` 等 6 部

🔴 症狀

小說	檔案大小	修復前章節	修復後章節
劍神重生	26 MB	1	317
醫道官途	32 MB	1	383
末日蟑螂	18 MB	7	7（待追）

🔍 根因（兩層）

第一層：原始 txt 檔無章節標題（論壇連載時樓主只貼正文）。

第二層：pattern_a 匹配到正文中的「第X章」引用，誤判為標題，導致 4 章覆蓋 1147 萬字。

🛠️ 修復過程（完整實錄）

診斷一：跑 Get-Content ... -TotalCount 30，確認前 30 行是書名/作者/簡介，無標題
診斷二：跑 Select-String "第.{1,6}[章回節卷]"，只抓到正文引用，無標題
診斷三：跑 Python 直接呼叫 split_into_chapters()，確認回傳 4 章（誤判）
修復一：convert_to_hugo.py 加 fallback（每 3000 字切一章）
修復二：加守門（章節數 < 10 → 強制 fallback）
驗證：單部測試 劍神重生 → 317 章
重跑：20 部批量轉換 → 全過，總章節 2918 → 3300
重建：Hugo 編譯 4721 頁
部署：Git push → Cloudflare Workers 自動部署
驗證：novels.ahpal.com/novels/jian-shen-chong-sheng/0002/ 回 200

🛠️ 修復代碼

# 在 split_into_chapters() 的 return chapters 之前加守門
if len(chapters) < 10:
    FALLBACK_CHARS = 3000
    chapters = []
    for i in range(0, len(text), FALLBACK_CHARS):
        chunk = text[i:i+FALLBACK_CHARS].strip()
        if chunk:
            num = (i // FALLBACK_CHARS) + 1
            chapters.append((f'第{num}節', chunk))
return chapters
        

🚨 教訓

第 103 個教訓：

「pattern 匹配不到」≠「檔案有問題」。

有可能是原始資料本身就沒有標題。

先看原始檔，再改 pattern。

第 104 個教訓：

章節數 < 10 就是異常。

正常小說不會只有 4 章。

異常數字要當成 bug 處理，不是當成「小檔正常」。

18. 🆕 技術債追蹤（v5.6）

#	項目	狀態	備註
1	`pattern_a` 未收緊到 `{0,30}`	待辦	目前靠 fallback + 守門處理
2	`mo-ri-zhang-lang` 18 MB / 7 章	待追	守門未觸發，需診斷
3	`jian-dao-du-shen` 原始 22 章 / 58 章	待追	可能 pattern_e 過度切章
4	備份檔案清理	30 天後	2026-10-15 清理 `convert_to_hugo.py.bak-*`
5	`novels.bak-20260915-021044` 清理	確認後	聯想上的舊備份，佔空間但無用途
6	🆕 兩台 Python 版本不一致	待辦	聯想 3.12.14 / 戴爾 3.14.6
7	🆕 兩台 openai 版本不一致	待辦	聯想 3.14.1 / 戴爾 2.45.0
8	🆕 `google-generativeai` 已棄用	已切換	改用 `google-genai`

19. 🆕 戴爾 → 聯想 SMB 轉移實錄（v5.5 新增）

📌 轉移背景

聯想（AHPAL-LENOVO） 是工作室的主力機，戴爾（DESKTOP-AKLAM99） 是外出機。因主力機需要完整的開發環境，將戴爾上的小說站專案（含 MySQL 備份、Hugo 專案、轉換腳本）完整轉移至聯想。

📋 轉移摘要

項目	值
來源	戴爾 `C:\Projects\ahpal_backup\backup-7.10.2025_06-35-38_flwsybvf675b\mysql`
目標	聯想同路徑
方式	SMB 共享 + Robocopy
戴爾 IP	`10.33.94.254`
聯想 IP	`10.33.94.198`
總大小	24.963 GB
總檔案	42,014
總目錄	4,835
失敗數	0
傳輸時間	1 小時 54 分 43 秒
平均速度	230 MB/分

🎯 完整轉移 SOP（14 步驟）

# 步驟 1：戴爾開 SMB 共享 New-SmbShare -Name "AHPAL-MySQL" -Path "C:\Projects\ahpal_backup\backup-7.10.2025_06-35-38_flwsybvf675b\mysql" -FullAccess "Everyone" Get-SmbShare -Name "AHPAL-MySQL" # 步驟 2：戴爾查 IP ipconfig | Select-String "IPv4" # 結果：10.33.94.254 # 步驟 3：聯想測連線 Test-NetConnection -ComputerName 10.33.94.254 -Port 445 # 結果：TcpTestSucceeded : True # 步驟 4：聯想看共享 net view \\10.33.94.254 # 結果：看到 AHPAL-MySQL # 步驟 5：聯想建目標目錄 New-Item -ItemType Directory -Path "C:\Projects\ahpal_backup\backup-7.10.2025_06-35-38_flwsybvf675b\mysql" -Force # 步驟 6：聯想 Dry Run（先看不搬） robocopy "\\10.33.94.254\AHPAL-MySQL" "C:\Projects\..." /E /L /NP /XD __pycache__ .git /R:2 /W:5 # 結果：24.963 GB / 42,014 檔案 / 4,835 目錄 # 步驟 7：聯想正式搬遷 robocopy "\\10.33.94.254\AHPAL-MySQL" "C:\Projects\..." /E /NP /XD __pycache__ .git /R:2 /W:5 | Tee-Object -FilePath "C:\robocopy-mysql.log" # 結果：0 失敗 / 1 小時 54 分 # 步驟 8：戴爾開 .git 共享 New-SmbShare -Name "AHPAL-Git" -Path "C:\Projects\...\hugo_site\.git" -FullAccess "Everyone" # 步驟 9：聯想複製 .git robocopy "\\10.33.94.254\AHPAL-Git" "C:\Projects\...\hugo_site\.git" /E /NP /R:2 /W:5 # 結果：549.43 MB / 0 失敗 # 步驟 10：聯想驗證 Git cd C:\Projects\...\hugo_site git remote -v git log --oneline -3 git status # 結果：remote 正確 / HEAD 685824a3 / working tree clean # 步驟 11：聯想安裝 Hugo winget install Hugo.Hugo.Extended --version 0.166.0 hugo version # 結果：hugo v0.166.0 extended # 步驟 12：聯想 Hugo 編譯驗證 hugo --minify # 結果：Pages 4721（與戴爾一致） # 步驟 13：聯想 SSH 驗證 ssh -T [email protected] # 結果：Hi praystone! # 步驟 14：聯想 Push 觸發部署 git commit --allow-empty -m "Test: 聯想轉移後部署驗證" git push origin main # 結果：Cloudflare Workers 版本歷史出現此 commit # 步驟 15：線上驗證 Invoke-WebRequest -Uri "https://novels.ahpal.com/" -Method Head -UseBasicParsing | Select-Object StatusCode # 結果：200 # 步驟 16：關閉戴爾共享 Remove-SmbShare -Name "AHPAL-MySQL" -Force Remove-SmbShare -Name "AHPAL-Git" -Force Get-SmbShare -Name "AHPAL-MySQL" -ErrorAction SilentlyContinue Get-SmbShare -Name "AHPAL-Git" -ErrorAction SilentlyContinue # 結果：無輸出（已移除）

⚠️ 遇到的問題與解決

問題	原因	解決
`Get-SmbShareAccess -Name *` 失敗	`-Name` 不接受萬用字元	改用 `Get-SmbShare \| Get-SmbShareAccess`
`cd cd C:\Projects\...`	多打一個 `cd`	只貼一次
`Get-Process: 找不到接受引數 'C:\...'`	複製時把提示字元 `PS C:\...>` 一起貼上	只貼指令，不貼提示字元
`git clone [email protected]:praystone/ahpal-novels.git .` 失敗	目錄非空	改用 Robocopy 複製 `.git` 目錄
`hugo: 無法將 'hugo' 字詞辨識`	聯想沒裝 Hugo	`winget install Hugo.Hugo.Extended --version 0.166.0`

🚨 轉移教訓

第 105 個教訓：

「SMB 共享是空的」≠「不用搬」。

共享可能是後來建的，不是原本就有。

第 106 個教訓：

Dry Run 先看，實際數字可能跟預估差很多。

預估 13GB，實際 25GB。

第 107 個教訓：

.git 用複製，不用 git clone .。

目錄非空時，clone 會失敗。

第 108 個教訓：

Hugo 版本要一致，連 Build Hash 都對。

v0.166.0 extended，一個字都不能少。

第 109 個教訓：

Everything up-to-date 不代表 SSH 沒問題。

要另外測 ssh -T [email protected]。

20. 🆕 聯想批次生產線復活實錄（v5.6 全新章節）

📌 背景

聯想原本沒有完整的 Python 環境，批次生產線從未在聯想上跑過。2026-09-16，首次嘗試在聯想上跑批次，發現多個套件缺失。

🔴 症狀與修復過程

階段	錯誤	修復
1	`ModuleNotFoundError: No module named 'requests'`	`pip install requests`
2	套件裝了，但批次還是找不到	發現 `python` 指向 Codex runtime，`pip` 指向系統 Python
3	`ModuleNotFoundError: No module named 'requests'`	用絕對路徑裝到 Codex runtime
4	`ImportError: cannot import name 'genai' from 'google'`	裝 `google-genai`（新套件）
5	批次成功生成 99 篇 AI 趨勢文章	✅ 完成

🎯 關鍵指令

# 1. 確認 Python 路徑
where.exe python
# 結果：
#   C:\Users\User\.cache\codex-runtimes\...\python.exe  ← Codex runtime
#   C:\Users\User\AppData\Local\Programs\Python\Python312\python.exe

# 2. 確認 pip 路徑
where.exe pip
# 結果：
#   C:\Users\User\AppData\Local\Programs\Python\Python312\Scripts\pip.exe

# 3. 用絕對路徑裝套件到 Codex runtime
& "C:\Users\User\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" -m pip install requests python-dotenv google-genai openai

# 4. 驗證
& "C:\Users\User\.cache\codex-runtimes\...\python.exe" -c "import requests, openai, dotenv; from google import genai; print('OK')"
# 結果：OK
        

📊 批次生成結果

項目	值
批次分類	AI 趨勢
待生成	99 篇
成功	99 篇
失敗	0 篇
API	Responses API + Reasoning
配圖	Pollinations AI（部分 HTTP 500 重試成功）
品質分數	75-85 分
部署	Git push → Cloudflare 自動部署

🚨 教訓

第 110 個教訓：

pip install 不等於「裝到批次用的 Python」。

要用 where.exe python 確認路徑，再用 & "python.exe" -m pip install。

第 111 個教訓：

google-generativeai 已棄用，要用 google-genai。

import 寫法：from google import genai。

第 112 個教訓：

openai 3.14.1 是真的，不是仿冒。

2026 年 SDK 已升到 3.x + httpx2。

第 113 個教訓：

Responses API 寫法正確，client.responses.create() 是官方 API。

失敗時自動降級至 Chat API。

21. 🆕 雙機同步 SOP（v5.5 全新章節）

🎯 日常同步流程

聯想（主力機）為開發中心，戴爾（外出機）為移動工作站。

兩台透過 Git 同步，確保內容一致。

📋 同步情境

情境	操作
聯想開發完，要同步到戴爾	聯想 push → 戴爾 pull
戴爾外出修改，要同步回聯想	戴爾 push → 聯想 pull
兩台都有修改，要合併	用 `git-manager.ps1` 選 [Y] 全部同步
衝突發生	用 `git-manager.ps1` 選 [P] 全部拉，強制以遠端為準

🛠️ 同步指令

# 聯想（主力機）推送
cd C:\Projects\...\hugo_site
git add .
git commit -m "Update: 聯想 - $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"
git push origin main

# 戴爾（外出機）拉取
cd C:\Projects\...\hugo_site
git pull origin main

# 或使用 git-manager.ps1
.\git-manager.ps1
# 選 [Y] 全部同步
        

⚠️ 同步前檢查清單

☐ git status 確認 working tree clean
☐ git remote -v 確認 remote 正確
☐ 兩台路徑完全相同
☐ Hugo 版本一致（v0.166.0 extended）
☐ .env 不進 Git
🆕 ☐ Python 套件版本一致（或至少都能跑）

22. 🆕 Python 環境建置 SOP（v5.6 全新章節）

🎯 適用情境

新機器要跑 AHPAL 批次生產線時，需要建置 Python 環境。

📋 完整步驟

# 步驟 1：確認 Python 路徑
where.exe python
where.exe pip

# 步驟 2：確認 Python 版本
python --version

# 步驟 3：確認 pip 對應的 Python
pip show pip | Select-String "Location"

# 步驟 4：裝套件（用絕對路徑，確保裝到對的 Python）
& "C:\Users\User\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" -m pip install requests python-dotenv google-genai openai

# 步驟 5：驗證
& "C:\Users\User\.cache\codex-runtimes\...\python.exe" -c "import requests, openai, dotenv; from google import genai; print('OK')"
# 結果：OK

# 步驟 6：跑批次 DryRun 測試
cd C:\Users\User\ahpal-static\scripts\auto-batch
.\auto-trend-batch.ps1 -DryRun

# 步驟 7：確認 API 客戶端能初始化
cd C:\Users\User\ahpal-static
python -c "from src.api_client import APIClient; c = APIClient(); print(c.get_current_api_info())"
        

📊 必要套件清單

套件	pip 名稱	用途
`requests`	`requests`	HTTP 請求
`dotenv`	`python-dotenv`	讀 `.env`
`google.genai`	`google-genai`	Gemini API（新）
`openai`	`openai`	DeepSeek API（OpenAI 相容）

⚠️ 注意：

不要裝 google-generativeai（已棄用）
不要裝 httpx（openai 3.x 用 httpx2）
用絕對路徑裝，不要只用 pip

23. 🆕 批次生產線故障排除 SOP（v5.6 全新章節）

🔍 故障診斷流程

# 步驟 1：看最新日誌
Get-ChildItem "C:\Users\User\ahpal-AI-archive\system-tools\system-reports\01-批次生成日誌\*.log" | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Tail 30

# 步驟 2：確認 Python 程序
Get-Process python -ErrorAction SilentlyContinue

# 步驟 3：確認 API Key
Get-Content "C:\Users\User\ahpal-env\.env" -Encoding UTF8 | Select-String "DEEPSEEK|GEMINI|TELEGRAM"

# 步驟 4：確認套件
python -c "import requests, openai, dotenv; from google import genai; print('OK')"

# 步驟 5：確認 Git 狀態
cd C:\Users\User\ahpal-static
git status
git log --oneline -3
        

📋 常見故障與解法

症狀	原因	解法
`ModuleNotFoundError: No module named 'requests'`	套件沒裝，或裝到錯的 Python	用絕對路徑重裝
`ImportError: cannot import name 'genai'`	裝到舊套件 `google-generativeai`	裝 `google-genai`
`❌ Responses API 生成失敗`	DeepSeek API 不支援或超時	自動降級至 Chat API
`⚠️ HTTP 500`（配圖）	Pollinations AI 臨時錯誤	重試 3 次，成功即繼續
`❌ 文章生成失敗`	API Key 無效或額度不足	檢查 `.env`、檢查餘額
批次卡住不動	Python 程序掛了	看日誌、重跑
Git push 失敗	衝突或網路問題	用 `git-manager.ps1` 選 [P] 拉，再推

🚨 批次中斷的處理

看日誌確認跑到哪一篇
如果 Python 程序還在，讓它跑完
如果 Python 程序掛了，重跑批次（會跳過已存在的）
如果 API 額度不足，等額度恢復或儲值

24. 🆕 災難復原 SOP（v5.6 更新）

🚨 情境一：聯想硬碟壞了

從 GitHub clone praystone/ahpal-novels
從戴爾的 SMB 共享（或外接硬碟）複製 mysql 目錄
安裝 Hugo v0.166.0 extended
設定 SSH key
建置 Python 環境（見第 22 章）
驗證 hugo --minify 頁數為 4,721
驗證 novels.ahpal.com 回 200

🚨 情境二：戴爾硬碟壞了

從聯想的 SMB 共享複製完整目錄
或從 GitHub clone + 聯想複製 SQL
安裝 Hugo v0.166.0 extended
設定 SSH key
建置 Python 環境
驗證

🚨 情境三：兩台都壞了

從 GitHub clone 所有 4 個 repo
從 SQL 備份還原（如果有的話）
或從備份硬碟還原
重新安裝 Hugo、設定 SSH、建置 Python 環境
重建排程（SYSTEM 帳戶）
驗證線上

🚨 情境四：.env 遺失

從備份還原 C:\Users\User\ahpal-env\.env
或重新申請 API Key：
- DeepSeek API Key
- Telegram Bot Token + Chat ID
- Gemini API Key
- GitHub Token
重建 .env（格式見 07-環境設定遮罩.txt）

🚨 情境五：Python 環境損壞

確認 where.exe python 的路徑
用絕對路徑重裝套件：
& "C:\Users\User\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" -m pip install requests python-dotenv google-genai openai
驗證：python -c "import requests, openai, dotenv; from google import genai; print('OK')"
跑批次 DryRun 測試